<html>
<head>
  <title>DWR (Direct Web Remoting)</title>
  <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"/>
</head>

<body>

<h1>DWR (Direct Web Remoting)</h1>

<h2>What DWR does for you:</h2>
<ul>
  <li>Gives you a very very easy way to call Java code from your web-app.</li>
  <li>Gives you a jump-start to being able to create GMail type interactivity.</li>
</ul>

<h2>What DWR does not do for you:</h2>
<ul>
  <li>Be a servlet framework</li>
  <li>Make coffee</li>
  <li>Be a perfect solution. Consider this alpha.</li>
</ul>

<h2>Steps to getting DWR running in your web app:</h2>

<h3>1. Copy the JAR file dwr.jar into the WEB-INF/lib directory of your webapp.</h3>

<h3>2. Add the following lines to your WEB-INF/web.xml</h3>
<pre>
  &lt;servlet>
    &lt;servlet-name>dwr-invoker&lt;/servlet-name>
    &lt;display-name>DWR Servlet&lt;/display-name>
    &lt;description>Direct Web Remoter Servlet&lt;/description>
    &lt;servlet-class>uk.ltd.getahead.dwr.DWRServlet&lt;/servlet-class>
      &lt;init-param>
         &lt;param-name>allowed&lt;/param-name>
         &lt;param-value>uk.ltd.getahead.dwr.test.Test java.util.Date&lt;/param-value>
         &lt;description>What classes do we allow access to?&lt;/description>
      &lt;/init-param>
      &lt;load-on-startup>-1&lt;/load-on-startup>
  &lt;/servlet>
  &lt;servlet-mapping>
    &lt;servlet-name>dwr-invoker&lt;/servlet-name>
    &lt;url-pattern>/dwr/*&lt;/url-pattern>
  &lt;/servlet-mapping>
</pre>
<p>
  You can change the <i>allowed</i> init-param to specify any classes you want, so long
  as they satisfy the following:
</p>
<ul>
  <li>The class must have a public no-args constructor like any normal Java Bean</li>
  <li>Avoid classes called by reserved JavaScript words. (methods called by reserved words are automatically excluded)</li>
  <li>There must be a way of converting from a string to all the parameter types. Currently the Coercer class converts Strings and all primitive types.</li>
  <li>Overridden methods will be involved in a bit of a lottery as to which gets called, so avoid overridden methods.</li>
  <li>Although you can allow several classes with the name last name component (like java.util.Date and java.sql.Date) you can't use them both in the same page.</li>
</ul>

<h3>3. Go to the following URL</h3>

<code>http://localhost:8080/[YOUR-WEBAPP]/dwr</code>
<p>
  You should see a page showing you the classes that you've selected in step 2.
  Having followed a link you should see an index of all the methods all ready for
  calling.
</p>
<p>Kick the tyres and have a look around.</p>
<p>To see more of how it works add the following lines to your web.xml</p>
<pre>
      &lt;init-param>
         &lt;param-name>debug&lt;/param-name>
         &lt;param-value>true&lt;/param-value>
         &lt;description>Do we begin in debug mode&lt;/description>
      &lt;/init-param>
</pre>
<p>This will prevent the Javascript from deleting the iframes that it creates</p>

<h3>4. How to make use of this from your web application</h3>

<p>
  Best practice is to have a class or 2 built to be called by DWR, this
  helps meet the marshalling requirements above and can help making thing secure
  (see below).
</p>
<p>
  The best way to get started is to nick the code from the demo pages:
</p>
<ul>
  <li>Go to http://localhost:8080/[YOUR-WEBAPP]/dwr and click on you class</li>
  <li>View source and find the line that executes the method that you are interested in.</li>
  <li>Paste the text into an HTML or JSP page in your web-app.</li>
  <li>Include links to the javascript files that make the magic happen:
<pre>
&lt;script src='/[YOUR-WEBAPP]/dwr/[YOUR-CLASS]/interface.js'>&lt;/script>
&lt;script src='/[YOUR-WEBAPP]/dwr/engine.js'>&lt;/script>
</pre>
</li>
  <li>You will probably need to customize the Javascript to fit your site.</li>
  <li>Dance the funky chicken (optional).</li>
</ul>

<h3>5. THINK ABOUT SECURITY</h3>
<p>
There is a danger that you could cause all sorts of security problems using this
code. You need to think about security earlier rather than later.
</p>
<p>
It makes sense to write your classes with DWR in mind thinking about the
restrictions in step 2 above. Don't accidentally include methods that would
allow an attacker to do too more that you wanted.
</p>
<p>
Access to dwr can be restricted using the declaritive security built into the
servlet spec.
</p>

<h3>Notes</h3>
<p>
The JavaBeans you write will function a bit like Stateless Session EJBs. The
differences are:
</p>
<ul>
  <li>DWR has no complex deployment and can be run from Tomcat without needing a full EJB server</li>
  <li>DWR is called directly from JavaScript without needing a separate web framework</li>
  <li>DWR does not do transactions, security but there are 101 frameworks that will give you those things.</li>
</ul>

</body>
</html>

<!--
sample home page templates    https://java-net.dev.java.net/ProjectPages.html
project page HTML             https://java-net.dev.java.net/pagedesign.html
-->
